
Help for sh Scripts Mode

                                        help version: 1.3
                                             created: 03/07/2000 {01:10:49 am}
                                         last update: 09/11/2001 {01:39:10 pm}


	  	Table of Contents

"# Abstract"
"# Description of files"
"# General Notes About sh Mode"

"# Specific Notes About sh Mode"
"#   Keywords"
"#   sh command double-click"
"#   sh File Marking"
"#   Adding a sh Prefs file"
"# Unix Commands Help"
"# The sh Scripts Menu"

"# Latest Versions"
"# Future Versions"
"# License and Disclaimer"

<<floatNamedMarks>>


	  	Abstract

This document describes the sh mode for the software Alpha.  
sh mode is useful for editing unix, linux, or osx shell scripts.


	  	Description of files


This package includes four files for the sh mode:

	"shScriptsMode.tcl"
	"shCompletions.tcl"
	"sh Tutorial.sh"

and

	C shell Mode Help  (this file)


	  	General Notes About sh Mode


(1)  This mode serves primarily to make it easier to write unix environment
     shell scripts -- it colorizes keywords, and sets some indentation,
     electric, word break, and commenting preferences.

(2)  sh mode contains a full set of electric completions, as well as a 
     Completions Tutorial via the  Config --> Mode Prefs  menu item.

(3)  The sh mode allows for user customization of keyword dictionaries 
     via the  "Config --> Mode Prefs --> Preferences"  dialog.  New keywords 
     and color changes will take effect immediately, without the need for 
     a restart or changing windows.
	 
(4)  Instructions for editing a shPrefs.tcl file are given below.  
     Any keywords added will not only be colorized, but included
     in the completions routines as well.

(5)  sh mode uses the Electric Return and Electric Tab features.
     These could, of course, be turned off.

(6)  sh mode has Mark File [M] and Parse Function {} capabilities.

(7)  Finally, on-line help is available for the sh mode through 
     command double-clicking.  The URL to which the keywords are sent 
     can be configured the the Mode Preferences dialog.


	======================================================================


	  	Specific Notes About sh Mode


	  	 	Keywords


Keyword dictionaries are available in the "shScriptsMode.tcl" file, along
with any relevant annotation.  Commands, flags, program names, common
system directories, file suffixes and a few symbols (including the $ magic
character) can all be colorized.

Keywords and functions are based on System V and Solaris 2.0, as found in
O'Reilly's Unix in a Nutshell, and OS version 5.7 bin directories.

Example syntax file:  "sh Example.sh"

For a different sh script example, which uses 'block' style formatting, try
this example: "sh Example.tsch".  Toggle the 'Navigate Blocks' preference to
change sh mode's file marking and navigation routines.

Completions Tutorial: "sh Tutorial.sh"


	  	 	sh command double-click


On-line help is available for Unix commands through command-double-clicking,
by sending the selected keyword to the menu item "Www Command Help" The URL
to which the keywords are sent can be changed through the Mode Preferences
dialog.  See the "# Unix Commands Help" section below for more details.

	---------------------------------------------------------------------

You can also command double-click on keyword defined programs, such as spss, 
stata, emacs, etc.  You will receive a dialog asking if you would like your 
browser to attempt to find the host name of http://www.<program>.com .  
This is probably of limited utility, but you can define additional programs 
through the preferences as well.


	  	 	sh File Marking

The default file marking routine recognizes all commands that start at the 
beginning of a line, as well as section marks such as this:

### Section Heading         Section Heading
#### Subsection Heading    * Subsection Heading
### -----                  --------------------

### section and divider marks are built into the sh Mark File.  If
the 'Mark Headers Only' preference is set, then these will be the only
marks that appear.

	--------------------------------------------------------------

An alternative marking scheme takes over if the 'Navigate Blocks' preference
is set, one that was constructed for my (perhaps) idiosyncratic use of unix
shell scripts.  I mainly use shell scripts them to run a series of syntax
files, tabbing each line and commenting them out as I build a statistical
analysis, so most of my commands are single lines.  Scripts can serve many
purposes, however, and shell commands can extend over several lines with
personalized styles of indentation, so one can adjust the Mark Expression
preference in the "Config --> Mode Preferences" dialog.

Note that there is also a regular expression preference available for 
Parsing Functions {} ; this item will only return the captured expression, 
not the line.  It's preference does not need to agree with the Mark Expression, 
and there might be good reason to have them catch different expressions.  

Here's how different regular expressions will mark and parse the file, with 
various uses of tabs and spaces.


	The file                 Mark File        Parse Functions
	______________________________________________________________________

^[ \t]*(\w+)          (the default setting)    (the default setting)

test1 xxx                   test1 xxx        test1            
____test2 xxx               test2 xxx        test2
\t    test3 xxx             test3 xxx        test3
________test4 xxx           test4 xxx        test4
\t    ____test5 xxx         test5 xxx        test5
____\t  ____test6 xxx       test6 xxx        test6
\t    \t    test7 xxx       test7 xxx        test7
# test8 xxx

	______________________________________________________________________

^[ \t]+(\w+)

test1                
____test2 xxx               test2 xxx        test2
\t    test3 xxx             test3 xxx        test3
________test4 xxx           test4 xxx        test4
\t    ____test5 xxx         test5 xxx        test5
____\t  ____test6 xxx       test6 xxx        test6
\t    \t    test7 xxx       test7 xxx        test7
# test8 xxx

	______________________________________________________________________

^[ \t](\w+)

test1 xxx
____test2 xxx
\t    test3 xxx             test3 xxx        test3
________test4 xxx
\t    ____test5 xxx
____\t  ____test6 xxx
\t    \t    test7 xxx        
# test8 xxx

	______________________________________________________________________

^[\t]*(\w+)

test1 xxx                   test1 xxx        test1
____test2 xxx            
\t    test3 xxx             test3 xxx        test3
________test4 xxx
\t    ____test5 xxx
____\t  ____test6 xxx
\t    \t    test7 xxx       test7 xxx        test7
# test8 xxx

	______________________________________________________________________

^[\t]+(\w+)

test1 xxx
____test2 xxx
\t    test3 xxx             test3 xxx        test3
________test4 xxx
\t    ____test5 xxx        
____\t  ____test6 xxx
\t    \t    test7 xxx       test7 xxx        test7
# test8 xxx

	______________________________________________________________________

^[ ]*(\w+)

test1 xxx                   test1 xxx        test1
____test2 xxx
\t    test3 xxx             test3 xxx        test3
________test4 xxx           test4 xxx        test4
\t    ____test5 xxx        
____\t  ____test6 xxx
\t    \t    test7 xxx
# test8 xxx

	______________________________________________________________________

^(\w+)

test1 xxx                   test1 xxx        test1
____test2 xxx
\t    test3 xxx
________test4 xxx
\t    ____test5 xxx
____\t  ____test6 xxx
\t    \t    test7 xxx
# test8 xxx

	______________________________________________________________________



This does not, of course, exhaust the possibilities of regular expressions.
For more information see the Alpha help file "Regular Expressions".  


	  	 	Adding a sh Prefs file


To add additional commands or arguments in an "shPrefs.tcl" file, go to
"Config --> Mode Prefs --> Edit Prefs File", and add these lines:


	set shUserCommands {
		blah bladdity
	}
	
	set shUserPrograms {
		blah2 bladdity2
	}
	
	set shUserFlags {
		blah3 bladdity3
	}
	
	sh::colorizesh


Include as many keywords as desired within the braces, separating each
keyword by at least one space or carriage return.  Alpha will automatically
load this preferences file the first that the sh mode is invoked.

Any keywords contained in these categories will not only be colorized, but
will also be included as electric completions.  Don't repeat commands or
arguments that have already been defined.


	  	Unix Commands Help

On-line help is available for any sh mode keyword, both through command
double-clicking and by using the "Www Command Help..." menu item.  The
behavior of these routines can be re-configured as desired by toggling the 
sh mode preference "Help Opens Man Page".

Here's an example of the difference between the two:

University of Edinburgh, Scotland

<http://unixhelp.ed.ac.uk/cgi-bin/unixhelp_search?search_term=rmdir&max_hits=20>
<http://unixhelp.ed.ac.uk/CGI/man-cgi?rmdir>

	--------------------------------------------------------------

If this preference is set, then keywords are sent to an on-line man pages
cgi-bin site, using the cgi script created and maintained by Panagiotis
Christias, <christia@ntua.gr>.  Here's another example:

    <http://www.ntua.gr/cgi-bin/man-cgi?ls>

There are several mirrors of this site available -- try entering the term
"man-cgi" in any search engine to locate them.  If you change the url, be
sure to include everything up to the question mark.

	--------------------------------------------------------------

If this preference is not set, then keywords are instead sent to the search
engine for "Unix Help for Users".  This site was developed at the University
of Edinburgh, and is freely distributed around the world for local
installation.  The mode is set up to send your query to the UK, but you can
change this in the Mode Preferences if want want a site that is closer (or
further away).

You'll find a list of mirror sites here:

<http://www.ucs.ed.ac.uk/~unixhelp/servers.html>

Once you've chosen one, do a search for your favorite command, and then pay 
attention to the URL that you ended up with.  Include the address up 
to the question mark, as in

	http://www.dmu.ac.uk/cgi-bin/unixhelp_search?

Here's some examples.

University of Edinburgh, Scotland

<http://unixhelp.ed.ac.uk/cgi-bin/unixhelp_search?search_term=rmdir&max_hits=20>

De Montfort University, East Midlands United Kingdom

<http://www.dmu.ac.uk/cgi-bin/unixhelp_search?search_term=rmdir&max_hits=20>

Jzsef Attila University, Szeged Hungary

<http://www.cab.u-szeged.hu/cgi-bin/unixhelp_search?search_term=rmdir&max_hits=20>

Swiss Federal Institute of Technology, Lausanne Switzerland

<http://dgrwww.epfl.ch/cgi-bin/unixhelp_search?search_term=rmdir&max_hits=20>

	--------------------------------------------------------------

Alphatk/8 users can also set the sh mode preference "Open Help Doc In Alpha"
preference to parse the file in Alpha, otherwise the urls will always be
opened in a local browser window.

	---------------------------------------------------------------------

Any available syntax information is also available by pressing the control 
key while command-double-clicking.  This information will appear in the 
status bar window.  In some cases, this information is too long to be read 
in its entirety.  Pressing the shift key instead of the control key will 
insert this syntax information as commented text into your current window.

NOTE: These control-command and shift-command double-click features have not
been fully implemented.  See the "shCompletions.tcl" file for additional 
information.


	  	The sh Scripts Menu

The menu associated with this mode contains the following items:

	sh Scripts Home Page

Opens the url specified in the "sh Scripts Home Page" url preference.


	Www Command Help

Opens a dialog like this --> <<sh::wwwCommandHelp>> allowing you to enter a
unix command to send to the various unix help urls.  See the section above 
on "# Unix Commands Help" for more information.


	sh Mode Options

This is a submenu allowing you to set some sh mode 'flag' preferences, or 
to open this file.


	New Comment

Inserts a new 'paragraph' style comment just prior to the current block of 
commands, such as this



The template can be customized using the menu item ...

Note that if the 'Navigate Blocks' preference is set, then the new comment 
will be inserted at the beginning of the current block, as defined by an
empty line.

	## 
	 # 
	 ##
		rm -f    ../data-temp
		ln -s    /var/scratch/benefits-cps/  ../data-temp/


	Comment Template

Creates (or changes) the 'sh Custom Template' preference.  Simply type in 
the custom template, highlight it, and then use this menu item to save the 
selected text as the template.  To create 'bullets' that you can navigate
with the tab key, be sure to insert two bullets for each stop.

	--------------------------------------------------------------

These next items will change depending on the 'Navigate Blocks' preference.

	Next Block/Command

Jump to the next 'block' of commands, as defined by being separated by at
least one empty line, or to the next command as determined by indentation.

	Prev Block/Command

Jump to the previous 'block' of commands, or the previous command as
determined by indentation.


These items are also bound to <control>-<shift>-<arrow keys>.  The up and
down arrows will simply move the cursor to the start of the next/prev
block/command.  Right and left arrows will also place this entry at the top
of the window.

These items are also bound to 1 and 3 on the keypad when numlock is turned
off.  These key bindings will place the next/prev block/command in the
center of the window.  The numlock in Alpha is toggled by holding down the
shift key when pressing "num-lock" on the keypad.

If any text is currently highlighted, all of these navigation items will
extend the current selection to the next/previous entry.


	Select Block/Command

Select the entire block/command in which the cursor currently resides.

	Reformat Block

Reformat the entire block/command in which the cursor currently resides.
This is essentially a shortcut for the menu items "Select Paragraph" and
"Indent Selection" normally found in the Edit and Text menus.


	======================================================================


	  	Latest Versions


The latest version of sh mode will be available at

	<http://www.princeton.edu/~cupright/computing/alpha/>

Updated versions will also be posted to Vince's upload site, 

	<ftp://ftp.ucsd.edu/pub/alpha/>

and announced on the AlphaTcl users mailing list.  (See the file "Readme"
for more information.)


	  	Future Versions


I submit this mode to the Alpha community with the hopes that (i) somebody
else will find it useful, (ii) any errors or updates will be reported to
me, and (iii) I might inspire somebody to take them even further.  I will
continue to maintain them and post updates as necessary, but any
contributions are certainly welcome.


	  	License and Disclaimer


Copyright (c) 2000-2001  Craig Barton Upright
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.

  Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.

  Neither the name of Alpha/Alphatk nor the names of its contributors may
   be used to endorse or promote products derived from this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.

This mode is free.  Alpha is shareware !   <<register>>


cheers,

-- Craig


Author: Craig Barton Upright
E-mail: <cupright@princeton.edu>
  mail: Princeton University,  Department of Sociology 
        Princeton, New Jersey  08544  USA
   www: <http://www.princeton.edu/~cupright/>


	  	Copyright

This document has been placed in the public domain
